M

MLOG

Nederlands

Leer schaalbare GraphQL-schemaontwerppatronen voor het bouwen van robuuste en onderhoudbare API's voor een divers, wereldwijd publiek. Beheers schema stitching, federatie en modularisatie.

GraphQL Schemaontwerp: Schaalbare Patronen voor Wereldwijde API's

GraphQL is uitgegroeid tot een krachtig alternatief voor traditionele REST API's, en biedt clients de flexibiliteit om precies de data op te vragen die ze nodig hebben. Echter, naarmate uw GraphQL API in complexiteit en omvang groeit – vooral wanneer deze een wereldwijd publiek met diverse datavereisten bedient – wordt een zorgvuldig schemaontwerp cruciaal voor onderhoudbaarheid, schaalbaarheid en prestaties. Dit artikel onderzoekt verschillende schaalbare GraphQL-schemaontwerppatronen om u te helpen robuuste API's te bouwen die de eisen van een wereldwijde applicatie aankunnen.

Het Belang van een Schaalbaar Schemaontwerp

Een goed ontworpen GraphQL-schema is de basis van een succesvolle API. Het dicteert hoe clients met uw data en services kunnen interageren. Een slecht schemaontwerp kan leiden tot een aantal problemen, waaronder:

Voor wereldwijde applicaties worden deze problemen versterkt. Verschillende regio's kunnen verschillende datavereisten, wettelijke beperkingen en prestatieverwachtingen hebben. Een schaalbaar schemaontwerp stelt u in staat om deze uitdagingen effectief aan te gaan.

Kernprincipes van Schaalbaar Schemaontwerp

Voordat we ingaan op specifieke patronen, laten we enkele kernprincipes schetsen die als leidraad moeten dienen voor uw schemaontwerp:

Schaalbare Schemaontwerppatronen

Hier zijn verschillende schaalbare schemaontwerppatronen die u kunt gebruiken om robuuste GraphQL API's te bouwen:

1. Schema Stitching

Schema stitching stelt u in staat om meerdere GraphQL API's te combineren tot één enkel, verenigd schema. Dit is met name handig wanneer verschillende teams of services verantwoordelijk zijn voor verschillende delen van uw data. Het is alsof u verschillende mini-API's hebt die u aan elkaar koppelt via een 'gateway'-API.

Hoe het werkt:

  1. Elk team of elke service stelt zijn eigen GraphQL API beschikbaar met een eigen schema.
  2. Een centrale gatewayservice gebruikt schema-stitching-tools (zoals Apollo Federation of GraphQL Mesh) om deze schema's samen te voegen tot één enkel, verenigd schema.
  3. Clients interageren met de gatewayservice, die verzoeken doorstuurt naar de juiste onderliggende API's.

Voorbeeld:

Stel u een e-commerceplatform voor met afzonderlijke API's voor producten, gebruikers en bestellingen. Elke API heeft zijn eigen schema:

  
    # Producten API
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # Gebruikers API
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # Bestellingen API
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
    }

    type Query {
      order(id: ID!): Order
    }

De gatewayservice kan deze schema's samenvoegen om een verenigd schema te creëren:

  
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Order {
      id: ID!
      user: User! @relation(field: "userId")
      product: Product! @relation(field: "productId")
      quantity: Int!
    }

    type Query {
      product(id: ID!): Product
      user(id: ID!): User
      order(id: ID!): Order
    }

Merk op hoe het Order-type nu verwijzingen naar User en Product bevat, ook al zijn deze types in afzonderlijke API's gedefinieerd. Dit wordt bereikt door middel van schema-stitching-richtlijnen (zoals @relation in dit voorbeeld).

Voordelen:

Overwegingen:

2. Schemafederatie

Schemafederatie is een evolutie van schema stitching, ontworpen om enkele van de beperkingen ervan aan te pakken. Het biedt een meer declaratieve en gestandaardiseerde aanpak voor het samenstellen van GraphQL-schema's.

Hoe het werkt:

  1. Elke service stelt een GraphQL API beschikbaar en annoteert zijn schema met federatierichtlijnen (bijv. @key, @extends, @external).
  2. Een centrale gatewayservice (die Apollo Federation gebruikt) gebruikt deze richtlijnen om een supergraph op te bouwen – een representatie van het gehele gefedereerde schema.
  3. De gatewayservice gebruikt de supergraph om verzoeken naar de juiste onderliggende services te routeren en afhankelijkheden op te lossen.

Voorbeeld:

Met hetzelfde e-commercevoorbeeld zouden de gefedereerde schema's er als volgt uit kunnen zien:

  
    # Producten API
    type Product @key(fields: "id") {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # Gebruikers API
    type User @key(fields: "id") {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # Bestellingen API
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
      user: User! @requires(fields: "userId")
      product: Product! @requires(fields: "productId")
    }

    extend type Query {
      order(id: ID!): Order
    }

Let op het gebruik van federatierichtlijnen:

Voordelen:

Overwegingen:

3. Modulair Schemaontwerp

Modulair schemaontwerp houdt in dat een groot, monolithisch schema wordt opgedeeld in kleinere, beter beheersbare modules. Dit maakt het gemakkelijker om individuele delen van uw API te begrijpen, aan te passen en opnieuw te gebruiken, zelfs zonder gebruik te maken van gefedereerde schema's.

Hoe het werkt:

  • Identificeer logische grenzen binnen uw schema (bijv. gebruikers, producten, bestellingen).
  • Creëer afzonderlijke modules voor elke grens, waarin de types, queries en mutaties met betrekking tot die grens worden gedefinieerd.
  • Gebruik import/export-mechanismen (afhankelijk van uw GraphQL-serverimplementatie) om de modules te combineren tot één enkel, verenigd schema.

    • Voorbeeld (met JavaScript/Node.js):

    Maak afzonderlijke bestanden voor elke module:

      
    // users.graphql
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    // products.graphql
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    Combineer ze vervolgens in uw hoofdschemabestand:

      
    // schema.js
    const { makeExecutableSchema } = require('graphql-tools');
    const { typeDefs: userTypeDefs, resolvers: userResolvers } = require('./users');
    const { typeDefs: productTypeDefs, resolvers: productResolvers } = require('./products');

    const typeDefs = [
      userTypeDefs,
      productTypeDefs,
      ""
    ];

    const resolvers = {
      Query: {
        ...userResolvers.Query,
        ...productResolvers.Query,
      }
    };

    const schema = makeExecutableSchema({
      typeDefs,
      resolvers,
    });

    module.exports = schema;

    Voordelen:

    Overwegingen:

    4. Interface- en Union-Types

    Interface- en union-types stellen u in staat om abstracte types te definiëren die door meerdere concrete types kunnen worden geïmplementeerd. Dit is handig voor het representeren van polymorfe data – data die verschillende vormen kan aannemen afhankelijk van de context.

    Hoe het werkt:

    Voorbeeld:

      
    interface Node {
      id: ID!
    }

    type User implements Node {
      id: ID!
      name: String!
      email: String!
    }

    type Product implements Node {
      id: ID!
      name: String!
      price: Float!
    }

    union SearchResult = User | Product

    type Query {
      node(id: ID!): Node
      search(query: String!): [SearchResult!]!
    }

    In dit voorbeeld implementeren zowel User als Product de Node-interface, die een gemeenschappelijk id-veld definieert. Het SearchResult-union-type vertegenwoordigt een zoekresultaat dat ofwel een User of een Product kan zijn. Clients kunnen het `search`-veld bevragen en vervolgens het `__typename`-veld gebruiken om te bepalen welk type resultaat ze hebben ontvangen.

    Voordelen:

    Overwegingen:

    5. Connection-Patroon

    Het connection-patroon is een standaardmanier om paginering in GraphQL API's te implementeren. Het biedt een consistente en efficiënte manier om grote lijsten met data in brokken op te halen.

    Hoe het werkt:

    Voorbeeld:

      
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type UserEdge {
      node: User!
      cursor: String!
    }

    type UserConnection {
      edges: [UserEdge!]!
      pageInfo: PageInfo!
    }

    type PageInfo {
      hasNextPage: Boolean!
      hasPreviousPage: Boolean!
      startCursor: String
      endCursor: String
    }

    type Query {
      users(first: Int, after: String, last: Int, before: String): UserConnection!
    }

    Voordelen:

    Overwegingen:

    Wereldwijde Overwegingen

    Wanneer u een GraphQL-schema ontwerpt voor een wereldwijd publiek, overweeg dan deze extra factoren:

    Neem bijvoorbeeld een veld voor productbeschrijving:

    
type Product {
 id: ID!
 name: String!
 description(language: String = "en"): String!
}

    Dit stelt clients in staat de beschrijving in een specifieke taal op te vragen. Als er geen taal is opgegeven, wordt standaard Engels (en) gebruikt.

    Conclusie

    Een schaalbaar schemaontwerp is essentieel voor het bouwen van robuuste en onderhoudbare GraphQL API's die de eisen van een wereldwijde applicatie aankunnen. Door de principes in dit artikel te volgen en de juiste ontwerppatronen te gebruiken, kunt u API's creëren die gemakkelijk te begrijpen, aan te passen en uit te breiden zijn, terwijl ze ook uitstekende prestaties en schaalbaarheid bieden. Vergeet niet uw schema te modulariseren, samen te stellen en te abstraheren, en rekening te houden met de specifieke behoeften van uw wereldwijde publiek.

    Door deze patronen te omarmen, kunt u het volledige potentieel van GraphQL ontsluiten en API's bouwen die uw applicaties nog jarenlang kunnen aandrijven.